home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 2.iso / dist / fw_gimp-print.idb / usr / freeware / info / gimpprint.info-1.z / gimpprint.info-1
Text File  |  2002-10-07  |  50KB  |  1,101 lines
  1. This is gimpprint.info, produced by makeinfo version 4.0 from
  2. gimpprint.texi.
  3.  
  4. INFO-DIR-SECTION Libraries
  5. START-INFO-DIR-ENTRY
  6. * GIMP-Print: (gimpprint).      print plugin for the GIMP, and printing library
  7. END-INFO-DIR-ENTRY
  8.  
  9.    This file documents the gimpprint library and associated programs
  10. used for high quality printing.
  11.  
  12.    Copyright (C) 2001 Michael Sweet (<mike@easysw.com>) and Robert
  13. Krawitz (<rlk@alum.mit.edu>)
  14.  
  15.    Permission is granted to make and distribute verbatim copies of this
  16. manual provided the copyright notice and this permission notice are
  17. preserved on all copies.
  18.  
  19.    Permission is granted to copy and distribute modified versions of
  20. this manual under the conditions for verbatim copying, provided that
  21. the entire resulting derived work is distributed under the terms of a
  22. permission notice identical to this one.
  23.  
  24.    Permission is granted to copy and distribute translations of this
  25. manual into another language, under the above conditions for modified
  26. versions, except that this permission notice may be stated in a
  27. translation approved by the Foundation.
  28.  
  29. 
  30. File: gimpprint.info,  Node: Top,  Prev: (dir),  Up: (dir)
  31.  
  32. The print plugin for the GIMP and printing library
  33. **************************************************
  34.  
  35.    This file documents the libgimpprint library and associated programs
  36. used for high quality printing. This edition documents version 4.2.2.
  37.  
  38.    *Note Problems::, for information on how to report problems with
  39. GIMP-Print.
  40.  
  41. * Menu:
  42.  
  43. * Instructions::                How to read this manual.
  44. * Copying::                     Your rights.
  45. * Overview::                    Preliminary information.
  46. * Using libgimpprint::          Examples of how to use libgimpprint.
  47. * Integrating libgimpprint::    Using libgimpprint in your own packages.
  48. * Functions::                   libgimpprint function reference.
  49. * Programs::                    Using GIMP-Print programs.
  50. * Problems::                    Reporting bugs.
  51. * Appendices::                  Additional information.
  52. * Data Type and Variable Index::  Index of data types and variables.
  53. * Function and Macro Index::    Index of functions and macros.
  54. * Concept Index::               Index of concepts.
  55.  
  56. 
  57. File: gimpprint.info,  Node: Instructions,  Next: Copying,  Prev: Top,  Up: Top
  58.  
  59. Preface
  60. *******
  61.  
  62.    This manual documents the use of the GIMP-Print package, focusing
  63. mainly on the libgimpprint library that is the core of GIMP-Print.
  64. Parts of the manual which describe the use of libgimpprint are aimed
  65. primarily at programmers, and do assume that the reader is familiar
  66. with C programming, and using standard programming tools on GNU or UNIX
  67. systems. Other parts of the manual document the use of the programs
  68. that make up the GIMP-Print package, and assume no knowledge other than
  69. the basics of using a shell and editor.
  70.  
  71.    The best way to learn how to use libgimpprint in your own programs
  72. is to read the manual from start to finish, using the examples given in
  73. the text to learn how it works. The bulk of the manual can be used as a
  74. reference once one understands the basics.
  75.  
  76.    The manual is split into several parts for the programmer.  It starts
  77. with a simple usage example of how to link a program with libgimpprint,
  78. then how to integrate this into package build scripts, using `make',
  79. `autoconf' and `automake'.  This is followed by a detailed function
  80. reference, including descriptions of all the data types used.
  81.  
  82.    For the end-user, there is a section on all of the programs that come
  83. with GIMP-Print, including the GIMP `print' plugin, and the CUPS and
  84. Ghostscript drivers.
  85.  
  86.    The appendices at the end of the manual detail the dither and weave
  87. algorithms used in libgimpprint, the ESC/P2 printer control language
  88. used in Epson printers and how to add support for a new printer to
  89. libgimpprint.
  90.  
  91.  
  92.  
  93.                   We hope you enjoy using GIMP-Print!
  94.  
  95.                        --The GIMP-Print project
  96.  
  97. 
  98. File: gimpprint.info,  Node: Copying,  Next: Overview,  Prev: Instructions,  Up: Top
  99.  
  100. GNU GENERAL PUBLIC LICENSE
  101. **************************
  102.  
  103.                          Version 2, June 1991
  104.  
  105.      Copyright (C) 1989, 1991 Free Software Foundation, Inc.
  106.      675 Mass Ave, Cambridge, MA 02139, USA
  107.      
  108.      Everyone is permitted to copy and distribute verbatim copies
  109.      of this license document, but changing it is not allowed.
  110.  
  111. Preamble
  112. ========
  113.  
  114.    The licenses for most software are designed to take away your
  115. freedom to share and change it.  By contrast, the GNU General Public
  116. License is intended to guarantee your freedom to share and change free
  117. software--to make sure the software is free for all its users.  This
  118. General Public License applies to most of the Free Software
  119. Foundation's software and to any other program whose authors commit to
  120. using it.  (Some other Free Software Foundation software is covered by
  121. the GNU Library General Public License instead.)  You can apply it to
  122. your programs, too.
  123.  
  124.    When we speak of free software, we are referring to freedom, not
  125. price.  Our General Public Licenses are designed to make sure that you
  126. have the freedom to distribute copies of free software (and charge for
  127. this service if you wish), that you receive source code or can get it
  128. if you want it, that you can change the software or use pieces of it in
  129. new free programs; and that you know you can do these things.
  130.  
  131.    To protect your rights, we need to make restrictions that forbid
  132. anyone to deny you these rights or to ask you to surrender the rights.
  133. These restrictions translate to certain responsibilities for you if you
  134. distribute copies of the software, or if you modify it.
  135.  
  136.    For example, if you distribute copies of such a program, whether
  137. gratis or for a fee, you must give the recipients all the rights that
  138. you have.  You must make sure that they, too, receive or can get the
  139. source code.  And you must show them these terms so they know their
  140. rights.
  141.  
  142.    We protect your rights with two steps: (1) copyright the software,
  143. and (2) offer you this license which gives you legal permission to copy,
  144. distribute and/or modify the software.
  145.  
  146.    Also, for each author's protection and ours, we want to make certain
  147. that everyone understands that there is no warranty for this free
  148. software.  If the software is modified by someone else and passed on, we
  149. want its recipients to know that what they have is not the original, so
  150. that any problems introduced by others will not reflect on the original
  151. authors' reputations.
  152.  
  153.    Finally, any free program is threatened constantly by software
  154. patents.  We wish to avoid the danger that redistributors of a free
  155. program will individually obtain patent licenses, in effect making the
  156. program proprietary.  To prevent this, we have made it clear that any
  157. patent must be licensed for everyone's free use or not licensed at all.
  158.  
  159.    The precise terms and conditions for copying, distribution and
  160. modification follow.
  161.  
  162.     TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  163.  
  164.   1. This License applies to any program or other work which contains a
  165.      notice placed by the copyright holder saying it may be distributed
  166.      under the terms of this General Public License.  The "Program",
  167.      below, refers to any such program or work, and a "work based on
  168.      the Program" means either the Program or any derivative work under
  169.      copyright law: that is to say, a work containing the Program or a
  170.      portion of it, either verbatim or with modifications and/or
  171.      translated into another language.  (Hereinafter, translation is
  172.      included without limitation in the term "modification".)  Each
  173.      licensee is addressed as "you".
  174.  
  175.      Activities other than copying, distribution and modification are
  176.      not covered by this License; they are outside its scope.  The act
  177.      of running the Program is not restricted, and the output from the
  178.      Program is covered only if its contents constitute a work based on
  179.      the Program (independent of having been made by running the
  180.      Program).  Whether that is true depends on what the Program does.
  181.  
  182.   2. You may copy and distribute verbatim copies of the Program's
  183.      source code as you receive it, in any medium, provided that you
  184.      conspicuously and appropriately publish on each copy an appropriate
  185.      copyright notice and disclaimer of warranty; keep intact all the
  186.      notices that refer to this License and to the absence of any
  187.      warranty; and give any other recipients of the Program a copy of
  188.      this License along with the Program.
  189.  
  190.      You may charge a fee for the physical act of transferring a copy,
  191.      and you may at your option offer warranty protection in exchange
  192.      for a fee.
  193.  
  194.   3. You may modify your copy or copies of the Program or any portion
  195.      of it, thus forming a work based on the Program, and copy and
  196.      distribute such modifications or work under the terms of Section 1
  197.      above, provided that you also meet all of these conditions:
  198.  
  199.        a. You must cause the modified files to carry prominent notices
  200.           stating that you changed the files and the date of any change.
  201.  
  202.        b. You must cause any work that you distribute or publish, that
  203.           in whole or in part contains or is derived from the Program
  204.           or any part thereof, to be licensed as a whole at no charge
  205.           to all third parties under the terms of this License.
  206.  
  207.        c. If the modified program normally reads commands interactively
  208.           when run, you must cause it, when started running for such
  209.           interactive use in the most ordinary way, to print or display
  210.           an announcement including an appropriate copyright notice and
  211.           a notice that there is no warranty (or else, saying that you
  212.           provide a warranty) and that users may redistribute the
  213.           program under these conditions, and telling the user how to
  214.           view a copy of this License.  (Exception: if the Program
  215.           itself is interactive but does not normally print such an
  216.           announcement, your work based on the Program is not required
  217.           to print an announcement.)
  218.  
  219.      These requirements apply to the modified work as a whole.  If
  220.      identifiable sections of that work are not derived from the
  221.      Program, and can be reasonably considered independent and separate
  222.      works in themselves, then this License, and its terms, do not
  223.      apply to those sections when you distribute them as separate
  224.      works.  But when you distribute the same sections as part of a
  225.      whole which is a work based on the Program, the distribution of
  226.      the whole must be on the terms of this License, whose permissions
  227.      for other licensees extend to the entire whole, and thus to each
  228.      and every part regardless of who wrote it.
  229.  
  230.      Thus, it is not the intent of this section to claim rights or
  231.      contest your rights to work written entirely by you; rather, the
  232.      intent is to exercise the right to control the distribution of
  233.      derivative or collective works based on the Program.
  234.  
  235.      In addition, mere aggregation of another work not based on the
  236.      Program with the Program (or with a work based on the Program) on
  237.      a volume of a storage or distribution medium does not bring the
  238.      other work under the scope of this License.
  239.  
  240.   4. You may copy and distribute the Program (or a work based on it,
  241.      under Section 2) in object code or executable form under the terms
  242.      of Sections 1 and 2 above provided that you also do one of the
  243.      following:
  244.  
  245.        a. Accompany it with the complete corresponding machine-readable
  246.           source code, which must be distributed under the terms of
  247.           Sections 1 and 2 above on a medium customarily used for
  248.           software interchange; or,
  249.  
  250.        b. Accompany it with a written offer, valid for at least three
  251.           years, to give any third party, for a charge no more than your
  252.           cost of physically performing source distribution, a complete
  253.           machine-readable copy of the corresponding source code, to be
  254.           distributed under the terms of Sections 1 and 2 above on a
  255.           medium customarily used for software interchange; or,
  256.  
  257.        c. Accompany it with the information you received as to the offer
  258.           to distribute corresponding source code.  (This alternative is
  259.           allowed only for noncommercial distribution and only if you
  260.           received the program in object code or executable form with
  261.           such an offer, in accord with Subsection b above.)
  262.  
  263.      The source code for a work means the preferred form of the work for
  264.      making modifications to it.  For an executable work, complete
  265.      source code means all the source code for all modules it contains,
  266.      plus any associated interface definition files, plus the scripts
  267.      used to control compilation and installation of the executable.
  268.      However, as a special exception, the source code distributed need
  269.      not include anything that is normally distributed (in either
  270.      source or binary form) with the major components (compiler,
  271.      kernel, and so on) of the operating system on which the executable
  272.      runs, unless that component itself accompanies the executable.
  273.  
  274.      If distribution of executable or object code is made by offering
  275.      access to copy from a designated place, then offering equivalent
  276.      access to copy the source code from the same place counts as
  277.      distribution of the source code, even though third parties are not
  278.      compelled to copy the source along with the object code.
  279.  
  280.   5. You may not copy, modify, sublicense, or distribute the Program
  281.      except as expressly provided under this License.  Any attempt
  282.      otherwise to copy, modify, sublicense or distribute the Program is
  283.      void, and will automatically terminate your rights under this
  284.      License.  However, parties who have received copies, or rights,
  285.      from you under this License will not have their licenses
  286.      terminated so long as such parties remain in full compliance.
  287.  
  288.   6. You are not required to accept this License, since you have not
  289.      signed it.  However, nothing else grants you permission to modify
  290.      or distribute the Program or its derivative works.  These actions
  291.      are prohibited by law if you do not accept this License.
  292.      Therefore, by modifying or distributing the Program (or any work
  293.      based on the Program), you indicate your acceptance of this
  294.      License to do so, and all its terms and conditions for copying,
  295.      distributing or modifying the Program or works based on it.
  296.  
  297.   7. Each time you redistribute the Program (or any work based on the
  298.      Program), the recipient automatically receives a license from the
  299.      original licensor to copy, distribute or modify the Program
  300.      subject to these terms and conditions.  You may not impose any
  301.      further restrictions on the recipients' exercise of the rights
  302.      granted herein.  You are not responsible for enforcing compliance
  303.      by third parties to this License.
  304.  
  305.   8. If, as a consequence of a court judgment or allegation of patent
  306.      infringement or for any other reason (not limited to patent
  307.      issues), conditions are imposed on you (whether by court order,
  308.      agreement or otherwise) that contradict the conditions of this
  309.      License, they do not excuse you from the conditions of this
  310.      License.  If you cannot distribute so as to satisfy simultaneously
  311.      your obligations under this License and any other pertinent
  312.      obligations, then as a consequence you may not distribute the
  313.      Program at all.  For example, if a patent license would not permit
  314.      royalty-free redistribution of the Program by all those who
  315.      receive copies directly or indirectly through you, then the only
  316.      way you could satisfy both it and this License would be to refrain
  317.      entirely from distribution of the Program.
  318.  
  319.      If any portion of this section is held invalid or unenforceable
  320.      under any particular circumstance, the balance of the section is
  321.      intended to apply and the section as a whole is intended to apply
  322.      in other circumstances.
  323.  
  324.      It is not the purpose of this section to induce you to infringe any
  325.      patents or other property right claims or to contest validity of
  326.      any such claims; this section has the sole purpose of protecting
  327.      the integrity of the free software distribution system, which is
  328.      implemented by public license practices.  Many people have made
  329.      generous contributions to the wide range of software distributed
  330.      through that system in reliance on consistent application of that
  331.      system; it is up to the author/donor to decide if he or she is
  332.      willing to distribute software through any other system and a
  333.      licensee cannot impose that choice.
  334.  
  335.      This section is intended to make thoroughly clear what is believed
  336.      to be a consequence of the rest of this License.
  337.  
  338.   9. If the distribution and/or use of the Program is restricted in
  339.      certain countries either by patents or by copyrighted interfaces,
  340.      the original copyright holder who places the Program under this
  341.      License may add an explicit geographical distribution limitation
  342.      excluding those countries, so that distribution is permitted only
  343.      in or among countries not thus excluded.  In such case, this
  344.      License incorporates the limitation as if written in the body of
  345.      this License.
  346.  
  347.  10. The Free Software Foundation may publish revised and/or new
  348.      versions of the General Public License from time to time.  Such
  349.      new versions will be similar in spirit to the present version, but
  350.      may differ in detail to address new problems or concerns.
  351.  
  352.      Each version is given a distinguishing version number.  If the
  353.      Program specifies a version number of this License which applies
  354.      to it and "any later version", you have the option of following
  355.      the terms and conditions either of that version or of any later
  356.      version published by the Free Software Foundation.  If the Program
  357.      does not specify a version number of this License, you may choose
  358.      any version ever published by the Free Software Foundation.
  359.  
  360.  11. If you wish to incorporate parts of the Program into other free
  361.      programs whose distribution conditions are different, write to the
  362.      author to ask for permission.  For software which is copyrighted
  363.      by the Free Software Foundation, write to the Free Software
  364.      Foundation; we sometimes make exceptions for this.  Our decision
  365.      will be guided by the two goals of preserving the free status of
  366.      all derivatives of our free software and of promoting the sharing
  367.      and reuse of software generally.
  368.  
  369.                                 NO WARRANTY
  370.  
  371.  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
  372.      WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
  373.      LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
  374.      HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
  375.      WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
  376.      NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  377.      FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
  378.      QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
  379.      PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  380.      SERVICING, REPAIR OR CORRECTION.
  381.  
  382.  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
  383.      WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
  384.      MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
  385.      LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
  386.      INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
  387.      INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
  388.      DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
  389.      OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
  390.      OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
  391.      ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  392.  
  393.                       END OF TERMS AND CONDITIONS
  394.  
  395. How to Apply These Terms to Your New Programs
  396. =============================================
  397.  
  398.    If you develop a new program, and you want it to be of the greatest
  399. possible use to the public, the best way to achieve this is to make it
  400. free software which everyone can redistribute and change under these
  401. terms.
  402.  
  403.    To do so, attach the following notices to the program.  It is safest
  404. to attach them to the start of each source file to most effectively
  405. convey the exclusion of warranty; and each file should have at least
  406. the "copyright" line and a pointer to where the full notice is found.
  407.  
  408.      ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
  409.      Copyright (C) 19YY  NAME OF AUTHOR
  410.      
  411.      This program is free software; you can redistribute it and/or
  412.      modify it under the terms of the GNU General Public License
  413.      as published by the Free Software Foundation; either version 2
  414.      of the License, or (at your option) any later version.
  415.      
  416.      This program is distributed in the hope that it will be useful,
  417.      but WITHOUT ANY WARRANTY; without even the implied warranty of
  418.      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  419.      GNU General Public License for more details.
  420.      
  421.      You should have received a copy of the GNU General Public License
  422.      along with this program; if not, write to the Free Software
  423.      Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  424.  
  425.    Also add information on how to contact you by electronic and paper
  426. mail.
  427.  
  428.    If the program is interactive, make it output a short notice like
  429. this when it starts in an interactive mode:
  430.  
  431.      Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
  432.      Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
  433.      type `show w'.  This is free software, and you are welcome
  434.      to redistribute it under certain conditions; type `show c'
  435.      for details.
  436.  
  437.    The hypothetical commands `show w' and `show c' should show the
  438. appropriate parts of the General Public License.  Of course, the
  439. commands you use may be called something other than `show w' and `show
  440. c'; they could even be mouse-clicks or menu items--whatever suits your
  441. program.
  442.  
  443.    You should also get your employer (if you work as a programmer) or
  444. your school, if any, to sign a "copyright disclaimer" for the program,
  445. if necessary.  Here is a sample; alter the names:
  446.  
  447.      Yoyodyne, Inc., hereby disclaims all copyright
  448.      interest in the program `Gnomovision'
  449.      (which makes passes at compilers) written
  450.      by James Hacker.
  451.      
  452.      SIGNATURE OF TY COON, 1 April 1989
  453.      Ty Coon, President of Vice
  454.  
  455.    This General Public License does not permit incorporating your
  456. program into proprietary programs.  If your program is a subroutine
  457. library, you may consider it more useful to permit linking proprietary
  458. applications with the library.  If this is what you want to do, use the
  459. GNU Library General Public License instead of this License.
  460.  
  461. Copying summary
  462. ***************
  463.  
  464.    GIMP-Print is "free"; this means that everyone is free to use it and
  465. free to redistribute it on a free basis. GIMP-Print is not in the public
  466. domain; it is copyrighted and there are restrictions on its
  467. distribution, but these restrictions are designed to permit everything
  468. that a good cooperating citizen would want to do. What is not allowed is
  469. to try to prevent others from further sharing any version of GIMP-Print
  470. that they might get from you.
  471.  
  472.    Specifically, we want to make sure that you have the right to give
  473. away copies of GIMP-Print, that you receive source code or else can get
  474. it if you want it, that you can change GIMP-Print or use pieces of it
  475. in new free programs, and that you know you can do these things.
  476.  
  477.    To make sure that everyone has such rights, we have to forbid you to
  478. deprive anyone else of these rights. For example, if you distribute
  479. copies of GIMP-Print, you must give the recipients all the rights that
  480. you have. You must make sure that they, too, receive or can get the
  481. source code. And you must tell them their rights.
  482.  
  483.    Also, for our own protection, we must make certain that everyone
  484. finds out that there is no warranty for GIMP-Print. If GIMP-Print is
  485. modified by someone else and passed on, we want their recipients to
  486. know that what they have is not what we distributed, so that any
  487. problems introduced by others will no reflect on our reputation.
  488.  
  489. 
  490. File: gimpprint.info,  Node: Overview,  Next: Using libgimpprint,  Prev: Copying,  Up: Top
  491.  
  492. Overview
  493. ********
  494.  
  495.    The GIMP-Print package is a collection of programs and a library for
  496. high quality printing on modern inkjets, including `photographic
  497. quality' models which offer very high resolutions and several inks.
  498.  
  499.    META: Short history of the project
  500.  
  501.    GIMP-Print is the print facility of the "GNU Image Manipulation
  502. Program" (GIMP). It is in addition a suite of drivers that may be used
  503. with common UNIX spooling systems using GhostScript or CUPS.  These
  504. drivers provide printing quality for UNIX/Linux on a par with
  505. proprietary vendor-supplied drivers in many cases, and can be used for
  506. many of the most demanding printing tasks.  The core of GIMP-Print is a
  507. shared library (libgimpprint) which may be used by any program that
  508. wishes to produce high-qulaity printed output.
  509.  
  510. 
  511. File: gimpprint.info,  Node: Using libgimpprint,  Next: Integrating libgimpprint,  Prev: Overview,  Up: Top
  512.  
  513. Using libgimpprint
  514. ******************
  515.  
  516.    This chapter describes how to write programs that use libgimpprint.
  517.  
  518. Code prerequisites
  519. ==================
  520.  
  521.    To use libgimpprint with a program, several steps must be taken:
  522.  
  523.   1. Include the master libgimpprint header `<gimp-print/gimp-print.h>.'
  524.  
  525.   2. Call `stp_init()'.
  526.  
  527.   3. Link with libgimpprint.
  528.  
  529.    The following is a short example program. It does not do anything
  530. useful, but it does everything required to link with libgimpprint and
  531. call other functions from libgimpprint.
  532.  
  533.      #include <gimp-print/gimp-print.h>
  534.      
  535.      int
  536.      main (int argc, char *argv[])
  537.      {
  538.        stp_init ();
  539.        return (0);
  540.      }
  541.  
  542. Linking with libgimpprint
  543. =========================
  544.  
  545.    To link a program with libgimpprint, then `-lgimpprint' needs to be
  546. passed to the compiler when linking. For example, to compile and link
  547. `prog.c' the following commands would be used:
  548.  
  549.      gcc -c prog.c
  550.      gcc -o prog -lgimpprint prog.o
  551.  
  552.    The compiler and linker flags needed may vary depending on the
  553. options GIMP-Print was configured with when it was built. The
  554. `gimpprint-config' script will give the correct parameters for the
  555. local installation (*note gimpprint-config::).
  556.  
  557. 
  558. File: gimpprint.info,  Node: Integrating libgimpprint,  Next: Functions,  Prev: Using libgimpprint,  Up: Top
  559.  
  560. Integrating libgimpprint
  561. ************************
  562.  
  563.    This chapter describes how to integrate the compiling and linking of
  564. programs using libgimpprint with build scripts. Commonly used systems
  565. include `make', but more commonly `Makefile' files are generated by
  566. using tools such as `autoconf' and `automake'.
  567.  
  568. * Menu:
  569.  
  570. * gimpprint-config::            Getting the correct compiler and linker flags
  571. * make::                        Normal makefiles
  572. * autoconf::                    Macro to automatically check for libgimpprint
  573. * automake::                    Automatically defined variables to use
  574.  
  575. 
  576. File: gimpprint.info,  Node: gimpprint-config,  Next: make,  Up: Integrating libgimpprint
  577.  
  578. `gimpprint-config'
  579. ==================
  580.  
  581.    Depending on the setup of the computer system GIMP-Print was
  582. installed on, as well as the options passed to `configure' when
  583. configuring the package when it was built, the `CFLAGS' and `LIBS'
  584. parameters needed to compile and link programs with libgimpprint may
  585. vary. To make it simple to determine what these are on any given
  586. system, the script `gimpprint-config' was created. It's job is to
  587. output the correct parameters for the setup on your system. The
  588. following options are available:
  589.  
  590.      roger@whinlatter:~/gimpprint/devel$ gimpprint-config --help
  591.      Usage: gimpprint-config [OPTIONS] [LIBRARIES]
  592.      Options:
  593.              [--prefix[=DIR]]
  594.              [--exec-prefix[=DIR]]
  595.              [--version]
  596.              [--libs]
  597.              [--cflags]
  598.      Libraries:
  599.              gimpprint
  600.  
  601.    The `--prefix' and `--exec-prefix' options are only needed if the
  602. installed locations of parts of GIMP-Print are different from the
  603. configured locations. These should never be needed if GIMP-Print was
  604. properly configured and installed.
  605.  
  606.    The installed version of GIMP-Print can be obtained with the
  607. `--version' option:
  608.  
  609.      roger@whinlatter:~/gimpprint/devel$ gimpprint-config --version
  610.      4.2.2
  611.  
  612.    The correct `CFLAGS' to use can be obtained with the `--cflags'
  613. option:
  614.  
  615.      roger@whinlatter:~/gimpprint/devel$ gimpprint-config --cflags
  616.  
  617.    In this case, there are no special `CFLAGS' required to compile
  618. programs.
  619.  
  620.    The correct `LIBS' to use can the obtained with the `--libs' option:
  621.  
  622.      roger@whinlatter:~/gimpprint/devel$ gimpprint-config --libs
  623.      -L/usr/lib -lgimpprint -lm
  624.  
  625.    The command can be used from the shell by enclosing it in backquotes
  626. ``':
  627.  
  628.      gcc `gimpprint-config --cflags` -c prog.c
  629.      gcc `gimpprint-config --libs` -o prog prog.o
  630.  
  631.    However, this is not the way it it typically used. Normally it is
  632. used in a `Makefile' (*note make::) or by an `m4' macro in a `configure'
  633. script (*note autoconf::).
  634.  
  635. 
  636. File: gimpprint.info,  Node: make,  Next: autoconf,  Prev: gimpprint-config,  Up: Integrating libgimpprint
  637.  
  638. `make'
  639. ======
  640.  
  641.    If you use `make' with your own `Makefile' files, then you are on
  642. your own. This manual offers no assistance with doing this. Only the
  643. following suggestion is offered:
  644.  
  645.      GIMPPRINT_VERSION = $(shell gimpprint-config --version)
  646.      GIMPPRINT_CFLAGS = $(shell gimpprint-config --cflags)
  647.      GIMPPRINT_LIBS = $(shell gimpprint-config --libs)
  648.  
  649.    How you choose to use these variables is entirely up to you. *note
  650. GNU make: (make)Top, for more information.
  651.  
  652. 
  653. File: gimpprint.info,  Node: autoconf,  Next: automake,  Prev: make,  Up: Integrating libgimpprint
  654.  
  655. `autoconf'
  656. ==========
  657.  
  658.    The `autoconf' program produces a Bourne shell script called
  659. `configure' from a template file called `configure.in'.  `configure.in'
  660. contains both Bourne shell script, and `m4' macros.  `autoconf' expands
  661. the `m4' macros into `real' shell script.  The resulting `configure'
  662. script performs various checks for installed programs, compiler
  663. characteristics and other system information such as available headers
  664. and libraries. *note GNU autoconf: (autoconf)Top, for more information.
  665.  
  666.    GIMP-Print provides an `m4' macro, `AM_PATH_GIMPPRINT', suitable for
  667. use in a `configure.in'. It defines the environment variables
  668. `GIMPPRINT_CFLAGS', `GIMPPRINT_LIBS' and `GIMPPRINT_CONFIG'. You can
  669. optionally specify a minimum version of the library to use, and shell
  670. script to run if the test suceeds or fails.
  671.  
  672.  - Macro: AM_PATH_GIMPPRINT ([MINIMUM-VERSION [, ACTION-IF-FOUND [,
  673.           ACTION-IF-NOT-FOUND]]])
  674.      Check for an installed version of GIMP-Print greater than or equal
  675.      to MINIMUM-VERSION.
  676.  
  677.      ACTION-IF-FOUND is a list of shell commands to run if the check
  678.      for the library succeeds; ACTION-IF-NOT-FOUND is a list of shell
  679.      commands to run if the check fails.
  680.  
  681.      The macro sets the following environment variables:
  682.      `GIMPPRINT_CFLAGS', `GIMPPRINT_LIBS' and `GIMPPRINT_CONFIG'. It
  683.      also will substitute them into any `Makefile.in' you specify in
  684.      `AC_OUTPUT' because it calls `AC_SUBST' for each of them. However,
  685.      you will probably be using `automake' to generate your
  686.      `Makefile.in' files (*note automake::).
  687.  
  688.  
  689. 
  690. File: gimpprint.info,  Node: automake,  Prev: autoconf,  Up: Integrating libgimpprint
  691.  
  692. `automake'
  693. ==========
  694.  
  695.    The `automake' program can be used to generate `Makefile.in' files
  696. suitable for use with a `configure' script generated by `autoconf'.  As
  697. `automake' _requires_ `autoconf', this section will assume the use of a
  698. `configure' script which uses the `AM_PATH_GIMPPRINT' macro (there is
  699. little point in _not_ using it!).
  700.  
  701.    It is highly recommeded that you use GNU `autoconf' and `automake'.
  702. They will allow you to make your software build on most platforms with
  703. most compilers. `automake' makes writing complex `Makefile' files very
  704. easy, by expressing how to build your packages in terms of what files
  705. are required to build a project and the installation locations of the
  706. files. It imposes a few limitations over using plain `Makefile' files,
  707. such as in the use of conditionals, but these problems are vastly
  708. outweighed by the benefits it brings. It also creates many extra
  709. targets in the generated `Makefile.in' files such as `dist',
  710. `distcheck', `clean', `distclean', `maintainer-clean' and `tags', and
  711. there are many more more available. *note GNU automake: (automake)Top,
  712. for more information.
  713.  
  714.    Because `AM_PATH_GIMPPRINT' calls `AC_SUBST' to substitute
  715. `GIMPPRINT_CFLAGS', `GIMPPRINT_LIBS' and `GIMPPRINT_CONFIG', `automake'
  716. will automatically set these variables in the `Makefile.in' files it
  717. generates, requiring no additional effort on your part!
  718.  
  719.    As in previous examples, we will make a program `prog' from a file
  720. `prog.c'. This is how one might build write a `Makefile.am' to do this:
  721.  
  722.      AUTOMAKE_OPTIONS = 1.4 gnu
  723.      MAINT_CHARSET = latin1
  724.      
  725.      @SET_MAKE@
  726.      
  727.      CFLAGS = @CFLAGS@
  728.      
  729.      INCLUDES = @INCLUDES@ $(GIMPPRINT_CFLAGS)
  730.      
  731.      bin_PROGRAMS = prog
  732.      prog_SOURCES = prog.c
  733.      prog_LDADD = $(GIMPPRINT_LIBS)
  734.      
  735.      MAINTAINERCLEANFILES = Makefile.in
  736.  
  737.    That's all there is to it! Please note that this example also
  738. requires the macro `AC_PROG_MAKE_SET' to be used in `configure.in' and
  739. the use of `AC_SUBST' to substitute `CFLAGS' and `INCLUDES' where
  740. `@CFLAGS@' and `@INCLUDES@' are found in the file, respectively.
  741.  
  742. 
  743. File: gimpprint.info,  Node: Functions,  Next: Programs,  Prev: Integrating libgimpprint,  Up: Top
  744.  
  745. Functions
  746. *********
  747.  
  748.    This section of the manual is a complete reference to all of the
  749. functions comprising libgimpprint, with examples.
  750.  
  751.    All of the libgimpprint functions can be declared by including the
  752. master libgimpprint header, `<gimp-print/gimp-print.h>'.  This should
  753. be done in every source file that uses gimpprint functions by putting
  754.  
  755.      #include <gimp-print/gimp-print.h>
  756.  
  757. at the top of each file.
  758.  
  759. * Menu:
  760.  
  761. * Main functions::              Essential functions every program must call.
  762. * stp_vars_t functions::        Using stp_vars_t.
  763. * Dither functions::            Dither algorithms.
  764. * Options functions::           Options.
  765. * Paper functions::             Paper size and orientation.
  766. * Printer functions::           Printer selection.
  767. * Settings functions::          Getting and changing settings.
  768. * Version functions::           Getting libgimpprint version information.
  769.  
  770. 
  771. File: gimpprint.info,  Node: Main functions,  Next: stp_vars_t functions,  Up: Functions
  772.  
  773. Main functions
  774. ==============
  775.  
  776.    These functions are essential to the correct functioning of
  777. libgimpprint.  All or most other functions in the library depend
  778. absolutely upon them.  In the case of `stp_init', this function _must_
  779. be called before any of the other functions in the library.
  780.  
  781.  - Function: int stp_init (void)
  782.      This function initialises the libgimpprint library. It must be
  783.      called before any of the other libgimpprint functions are called.
  784.      It is responsible for setting up message catalogues (for
  785.      internationalisation). This function may be called more than once,
  786.      at any stage during the execution of a program.
  787.  
  788.      It returns zero on success, nonzero on failure.
  789.  
  790.    `stp_init' might be used as follows:
  791.  
  792.      int
  793.      main (int argc, char **argv)
  794.      {
  795.        stp_init();
  796.      
  797.        ...
  798.      
  799.      }
  800.  
  801.  - Function: void * stp_malloc (size_t SIZE)
  802.      Where SIZE is the amount of memory to allocate (in bytes).
  803.  
  804.      This function allocates memory. It will always return a pointer to
  805.      the allocated memory. It will not return on failure.
  806.  
  807.      It returns a pointer to the allocated memory.
  808.  
  809. 
  810. File: gimpprint.info,  Node: stp_vars_t functions,  Next: Dither functions,  Prev: Main functions,  Up: Functions
  811.  
  812. `stp_vars_t' functions
  813. ======================
  814.  
  815.  - Data type: void * stp_vars_t
  816.      This is an opaque data type, whose structure is not visible to the
  817.      user.  This object contains all of the information about settings
  818.      for a given printer, such as color (contrast, brightness), the
  819.      type of printer, the dithering algorithm in use, and so forth.
  820.      Please see the `stp_set_*' and `stp_get_*' functions below for the
  821.      accessors and mutators for this data type.
  822.  
  823.  - Function: stp_vars_t stp_allocate_vars (void)
  824.      Allocate a new `stp_vars_t' with default settings for all members.
  825.  
  826.  - Function: void stp_copy_vars (stp_vars_t VD, const stp_vars_t VS)
  827.      Copy the settings from VS to VD.
  828.  
  829.  - Function: stp_vars_t stp_allocate_copy (const stp_vars_t VS)
  830.      Allocate a new `stp_vars_t', copying settings from VS.
  831.  
  832.  - Function: void stp_free_vars (stp_vars_t VV)
  833.      Free all resources associated with VV.  VV must not be used in any
  834.      way following this call.
  835.  
  836.  - Function: const char * stp_get_output_to (const stp_vars_t VV)
  837.  - Function: void stp_set_output_to (stp_vars_t VV, const char *VAL)
  838.  - Function: void stp_set_output_to_n (stp_vars_t VV, const char *VAL,
  839.           int BYTES)
  840.      Get or set the name of the command that this job will be printed
  841.      to.  This is used by front ends; the driver library always prints
  842.      to a stream provided by the front end and never uses this directly.
  843.  
  844.  - Function: const char * stp_get_driver (const stp_vars_t VV)
  845.  - Function: void stp_set_driver (stp_vars_t VV, const char *VAL)
  846.  - Function: void stp_set_driver_n (stp_vars_t VV, const char *VAL, int
  847.           BYTES)
  848.      Get or set the name of the driver (the type of printer).
  849.  
  850.  - Function: const char * stp_get_ppd_file (const stp_vars_t VV)
  851.  - Function: void stp_set_ppd_file (stp_vars_t VV, const char *VAL)
  852.  - Function: void stp_set_ppd_file_n (stp_vars_t VV, const char *VAL,
  853.           int BYTES)
  854.      Get or set the name of the PPD file used by this print job.
  855.      Normally, only PostScript printers use PPD files.
  856.  
  857.  - Function: const char * stp_get_resolution (const stp_vars_t VV)
  858.  - Function: void stp_set_resolution (stp_vars_t VV, const char *VAL)
  859.  - Function: void stp_set_resolution_n (stp_vars_t VV, const char *VAL,
  860.           int BYTES)
  861.      Get or set the resolution to be used in this print job.  Different
  862.      drivers support different resolutions, and many drivers support
  863.      multiple quality settings for a given DPI resolution.
  864.  
  865.  - Function: const char * stp_get_media_size (const stp_vars_t VV)
  866.  - Function: void stp_set_media_size (stp_vars_t VV, const char *VAL)
  867.  - Function: void stp_set_media_size_n (stp_vars_t VV, const char *VAL,
  868.           int BYTES)
  869.      Get or set the name of the media size (e. g. A3, letter, legal) to
  870.      be used in this print job.
  871.  
  872.  - Function: const char * stp_get_media_type (const stp_vars_t VV)
  873.  - Function: void stp_set_media_type (stp_vars_t VV, const char *VAL)
  874.  - Function: void stp_set_media_type_n (stp_vars_t VV, const char *VAL,
  875.           int BYTES)
  876.      Get or set the name of the media type (e. g. plain paper, photo
  877.      quality inkjet paper) to be used in this print job.
  878.  
  879.  - Function: const char * stp_get_media_source (const stp_vars_t VV)
  880.  - Function: void stp_set_media_source (stp_vars_t VV, const char *VAL)
  881.  - Function: void stp_set_media_source_n (stp_vars_t VV, const char
  882.           *VAL, int BYTES)
  883.      Get or set the name of the media source (e. g. manual feed, tray
  884.      A) to be used in this print job.
  885.  
  886.  - Function: const char * stp_get_ink_type (const stp_vars_t VV)
  887.  - Function: void stp_set_ink_type (stp_vars_t VV, const char *VAL)
  888.  - Function: void stp_set_ink_type_n (stp_vars_t VV, const char *VAL,
  889.           int BYTES)
  890.      Get or set the name of the ink type (e. g. four color standard, six
  891.      color photo) to be used in this print job.
  892.  
  893.  - Function: const char * stp_get_dither_algorithm (const stp_vars_t VV)
  894.  - Function: void stp_set_dither_algorithm (stp_vars_t VV, const char
  895.           *VAL)
  896.  - Function: void stp_set_dither_algorithm_n (stp_vars_t VV, const char
  897.           *VAL, int BYTES)
  898.      Get or set the dither algorithm to be used in this print job.
  899.  
  900.  - Function: int stp_get_output_type (const stp_vars_t VV)
  901.  - Function: void stp_set_output_type (stp_vars_t VV, int VAL)
  902.      Get or set the output type (color, grayscale, black and white) for
  903.      this print job.
  904.  
  905.  - Function: int stp_get_orientation (const stp_vars_t VV)
  906.  - Function: void stp_set_orientation (stp_vars_t VV, int VAL)
  907.      Get or set the paper orientation for this print job.
  908.  
  909.  - Function: int stp_get_left (const stp_vars_t VV)
  910.  - Function: void stp_set_left (stp_vars_t VV, int VAL)
  911.      Get or set the left margin (in 1/72 inch units, or "points") for
  912.      this print job.
  913.  
  914.  - Function: int stp_get_top (const stp_vars_t VV)
  915.  - Function: void stp_set_top (stp_vars_t VV, int VAL)
  916.      Get or set the top margin (in 1/72 inch units, or "points") for
  917.      this print job.
  918.  
  919.  - Function: int stp_get_image_type (const stp_vars_t VV)
  920.  - Function: void stp_set_image_type (stp_vars_t VV, int VAL)
  921.      Get or set the image type (line art, continuous tone, solid colors)
  922.      for this print job.
  923.  
  924.  - Function: int stp_get_unit (const stp_vars_t VV)
  925.  - Function: void stp_set_unit (stp_vars_t VV, int VAL)
  926.      Get or set the base unit (inches or centimeters) for this print
  927.      job.  This is provided for front ends; the package itself uses
  928.      points as its unit of measurement.
  929.  
  930.  - Function: int stp_get_page_width (const stp_vars_t VV)
  931.  - Function: void stp_set_page_width (stp_vars_t VV, int VAL)
  932.      Get or set the width of the printed region of the page.
  933.  
  934.  - Function: int stp_get_page_height (const stp_vars_t VV)
  935.  - Function: void stp_set_page_height (stp_vars_t VV, int VAL)
  936.      Get or set the height of the printed region of the page.
  937.  
  938.  - Function: int stp_get_input_color_model (const stp_vars_t VV)
  939.  - Function: void stp_set_input_color_model (stp_vars_t VV, int VAL)
  940.      Get or set the color model (currently RGB or CMY) of the input to
  941.      the driver.  Most front ends will use RGB input.
  942.  
  943.  - Function: int stp_get_output_color_model (const stp_vars_t VV)
  944.  - Function: void stp_set_output_color_model (stp_vars_t VV, int VAL)
  945.      Get or set the color model (currently RGB or CMY) of the output of
  946.      the driver.  Most printers will use CMY.
  947.  
  948.  - Function: float stp_get_scaling (const stp_vars_t VV)
  949.  - Function: void stp_set_scaling (stp_vars_t VV, float VAL)
  950.      Get or set the scaling factor of the image.  If the scaling factor
  951.      is greater than 0, it is interpreted as a percent (5.0-100.0 is
  952.      the valid range) of the printable page region, using the more
  953.      restrictive axis.  For example, if the image to be printed should
  954.      be 3" (wide) x 2" (high), and the printable page region is
  955.      8"x10.5", the scale factor should be 37.5 (3"/8").
  956.  
  957.      If the scaling is less than zero, it is interpreted as pixels per
  958.      inch.
  959.  
  960.      It is likely that in the future this will be migrated into the
  961.      front end.  There is no particular reason why the driver needs to
  962.      know about this.
  963.  
  964.  - Function: float stp_get_gamma (const stp_vars_t VV)
  965.  - Function: void stp_set_gamma (stp_vars_t VV, float VAL)
  966.      Get or set the gamma of the print job (valid range: 0.1-4.0;
  967.      default 1.0).  Note that this is not the absolute gamma used by
  968.      the print job; it is scaled by the gamma appropriate for the
  969.      printer.  This is true for all of the numerical parameters.
  970.  
  971.  - Function: float stp_get_brightness (const stp_vars_t VV)
  972.  - Function: void stp_set_brightness (stp_vars_t VV, float VAL)
  973.      Get or set the brightness of the print job (valid range: 0.0-2.0;
  974.      default: 1.0).  Any value other than 1.0 will result in some
  975.      possible values not being used; if brightness is less than 1.0, no
  976.      output point will be pure white, and if brightness is greater than
  977.      1.0, no output point will be pure black (or cyan, or magenta, or
  978.      yellow).
  979.  
  980.  - Function: float stp_get_contrast (const stp_vars_t VV)
  981.  - Function: void stp_set_contrast (stp_vars_t VV, float VAL)
  982.      Get or set the contrast of the print job (valid range: 0.0-4.0;
  983.      default: 1.0).  Values less than 1.0 will result in pure white or
  984.      black not being used (0.0 will make the entire image 50% gray).
  985.      Values greater than 1.0 do not hard clip; while the contrast in the
  986.      midtones increases, it only asymptotically approaches the limits.
  987.  
  988.  - Function: float stp_get_cyan (const stp_vars_t VV)
  989.  - Function: void stp_set_cyan (stp_vars_t VV, float VAL)
  990.      Get or set the cyan adjustment of the print job (range: 0.0-4.0;
  991.      default: 1.0).  This currently adjusts the gamma of the cyan
  992.      curve.  It is scaled by the cyan adjustment for the printer model
  993.      in question.
  994.  
  995.  - Function: float stp_get_magenta (const stp_vars_t VV)
  996.  - Function: void stp_set_magenta (stp_vars_t VV, float VAL)
  997.      Get or set the magenta adjustment of the print job (range:
  998.      0.0-4.0; default: 1.0).  This currently adjusts the gamma of the
  999.      magenta curve.  It is scaled by the magenta adjustment for the
  1000.      printer model in question.
  1001.  
  1002.  - Function: float stp_get_yellow (const stp_vars_t VV)
  1003.  - Function: void stp_set_yellow (stp_vars_t VV, float VAL)
  1004.      Get or set the yellow adjustment of the print job (range: 0.0-4.0;
  1005.      default: 1.0).  This currently adjusts the gamma of the yellow
  1006.      curve.  It is scaled by the yellow adjustment for the printer
  1007.      model in question.
  1008.  
  1009.  - Function: float stp_get_saturation (const stp_vars_t VV)
  1010.  - Function: void stp_set_saturation (stp_vars_t VV, float VAL)
  1011.      Get or set the saturation of the print job (range: 0.0-9.0;
  1012.      default: 1.0).  Saturation of 0.0 produces grayscale output using
  1013.      composite (CMY or CMYK, as appropriate for the printer) color.
  1014.  
  1015.  - Function: float stp_get_density (const stp_vars_t VV)
  1016.  - Function: void stp_set_density (stp_vars_t VV, float VAL)
  1017.      Get or set the density of the print job (range: 0.0-2.0; default:
  1018.      1.0).  This adjusts the amount of ink deposited in a linear fashion
  1019.      for all channels.  It is scaled by the density appropriate for the
  1020.      choice of printer, resolution, paper type, and other factors that
  1021.      the driver may deem appropriate.
  1022.  
  1023.  - Function: float stp_get_app_gamma (const stp_vars_t VV)
  1024.  - Function: void stp_set_app_gamma (stp_vars_t VV, float VAL)
  1025.      Get or set the gamma of the input (i. e. what the driving
  1026.      application uses).
  1027.  
  1028.  - Function: void * stp_get_lut (const stp_vars_t VV)
  1029.  - Function: void stp_set_lut (stp_vars_t VV, void *VAL)
  1030.      Get or set the color lookup table for the print job.  This is
  1031.      useful outside of the library for computing a preview of the
  1032.      printed result.  The lookup table itself should be treated as an
  1033.      opaque handle.
  1034.  
  1035.  - Function: unsigned char * stp_get_cmap (const stp_vars_t VV)
  1036.  - Function: void stp_set_cmap (stp_vars_t VV, unsigned char *VAL)
  1037.      Get or set the color map for the print job.  This is a table of
  1038.      R,G,B values for 8-bit indexed input.  This may be moved outside
  1039.      of the library in the future; in this case, the front end would be
  1040.      required to do its own mapping and supply true-color RGB to the
  1041.      driver.
  1042.  
  1043.    The following methods are used to perform output and error reporting
  1044. by the driver.  The driver supplies a stream of output bytes; the front
  1045. end is responsible for providing methods that accept this output and
  1046. handle it appropriately.
  1047.  
  1048.  - Function: stp_outfunc_t stp_get_outfunc (const stp_vars_t VV)
  1049.  - Function: void stp_set_outfunc (const stp_vars_t VV, stp_outfunc_t
  1050.           VAL)
  1051.  - Function: void * stp_get_outdata (const stp_vars_t VV)
  1052.  - Function: void stp_set_outdata (stp_vars_t VV, void *VAL)
  1053.       - Data type:  stp_outfunc_t
  1054.                typedef void (*stp_outfunc_t) (void *data,
  1055.                              const char *buffer, size_t bytes);
  1056.      Get or set the output function the driver will use.  The
  1057.      front end must supply a suitable function for accepting the output
  1058.      data.  The `stp_set_outdata' method provides a way of passing an
  1059.      appropriate object to the output function.
  1060.  
  1061.  - Function: stp_outfunc_t stp_get_errfunc (const stp_vars_t VV)
  1062.  - Function: void stp_set_errfunc (const stp_vars_t VV, stp_outfunc_t
  1063.           VAL)
  1064.  - Function: void * stp_get_errdata (const stp_vars_t VV)
  1065.  - Function: void stp_set_errdata (stp_vars_t VV, void *VAL)
  1066.      Get or set the error reporting function that the driver will use.
  1067.      This is used to report errors or debugging information, and must be
  1068.      supplied.  A typical errfunc will simply print whatever it's
  1069.      passed to stderr.
  1070.  
  1071.    /*  * hue_map is an array of 49 doubles representing the mapping of
  1072. hue  * from (0..6) to (0..6) in increments of .125.  The hue_map is in
  1073. CMY space,  * so hue=0 is cyan.   */ typedef void
  1074. (*stp_convert_t)(const stp_vars_t vars, const unsigned char *in,
  1075.                       unsigned short *out, int *zero_mask,
  1076.                  int width, int bpp, const unsigned char *cmap,
  1077.                       const double *hue_map, const double *lum_map,
  1078.                           const double *sat_map);
  1079.  
  1080.  - Function: void stp_merge_printvars (stp_vars_t USER, const
  1081.           stp_vars_t PRINT)
  1082.  
  1083.  - Function: void stp_allocate_lut (stp_vars_t V, size_t STEPS)
  1084.  
  1085.  - Function: void stp_free_lut (stp_vars_t V)
  1086.  
  1087.  - Function: void stp_compute_lut (stp_vars_t V, size_t STEPS)
  1088.  
  1089. 
  1090. File: gimpprint.info,  Node: Dither functions,  Next: Options functions,  Prev: stp_vars_t functions,  Up: Functions
  1091.  
  1092. Dither functions
  1093. ================
  1094.  
  1095.  - Function: size_t stp_dither_algorithm_count (void)
  1096.  
  1097.  - Function: const char * stp_dither_algorithm_name (int ID)
  1098.  
  1099.  - Function: const char * stp_default_dither_algorithm (void)
  1100.  
  1101.